Skip to content

Getting Started


adaptor:ex helps you to create interactive performances, theatre games, installations, chatbot adventures, alternate reality games or escape rooms. The graphical programming interface is optimized to bring dramaturgy and game mechanics together and to arrange them clearly.

You can make quick adjustments during rehearsals, monitor and control the live flow during testing and performance.

The adaptor:ex editor can be accessed through the browser, so multiple people can edit and control the same game in collaboration.

Screenshot: the adaptor:ex editor

Here you can find more about how to use adaptor:ex to wire and control your storyline, game mechanics, software and hardware.

Get and install adaptor:ex on your local machine or a server. There are different ways to Install.

Start with a Tutorial if you want to learn about one of the different ways you can use adaptor:ex.

The basic building Blocks, Actions and Plugins are described in more detail in Glossary.


To install adaptor:ex you currently have to use the command line of your operating system. On macOS, look for the "Terminal" program. On Linux you can find the terminal under the key combination [Ctrl]+[Alt]+[T]. On Windows search for the application "Input Prompt" or "Command line".

There are three installation options to choose from: NPM, SOURCE and DOCKER.

If you want to use the ports on your computer, e.g. the serial port via USB or a sound card, install adaptor:ex with NPM or via SOURCE.

Especially for a server installation we recommend installing in a Docker container.

adaptor:ex has just started. We'll be fixing bugs, improving things (hopefully) and adding new features frequently over the coming months. Occasionally update via NPM or Docker to stay current.

Contact us if you're having trouble installing adaptor:ex. Write to us at or check out our Discord.


Before you can continue to install adaptor:ex, you need the latest version of NodeJS. You can find the necessary installation files for your operating system here.

Once you have installed NodeJS, open your console or terminal and run the installation with npm in the command line

On macOS and Linux

sudo npm install -g adaptorex --unsafe-perm

On Windows

npm install -g adaptorex --unsafe-perm

If the installation was successful, start adaptor:ex with the command


You can find options for configuring adaptor:ex in the adaptor:ex server readme

To exit the adaptor:ex server use the key combination [Ctrl] + [C] (windows/linux) or [Cmd] + [C] (MacOS), or quit enter in the console.

Update with NPM

Download the latest version of adaptor:ex by repeating the installation above.

With npm outdated -g you can check whether a new version is available.

Installing Source with NPM

Before you can continue installing adaptor:ex, you need the latest version of NodeJS. You can find the necessary installation files for your operating system here .

Get adaptor:ex server and client:

Server Clone or download the latest adaptor:ex server GitLab repository here:

Client Clone or download the latest adaptor:ex client GitLab repository here:

Now you can install the server and client locally using NPM.

In the terminal (the console) change to the directory in which you loaded or cloned the server or client.

cd adaptor_ex_server/


cd adaptor_ex_client/

When you are in the correct directory run the following command

npm install

If the installation was successful, start the adaptor:ex server in the appropriate directory with the command

node index.js

Then, in a separate command line, start the adaptor:ex client in the appropriate directory with the command

npm run serve

Update with GIT

Download the latest version of adaptor:ex server and client by updating the Git repository in the respective directory with the following command updates

git pull

Then restart the adapter server and client.

Install Telegram extantion

In order to be able to use the Telegram plugin in adaptor:ex you have to additionally install python and some python libraries. Follow the instructions of the adaptor:ex Telegram Plugin Readme .

Install with Docker

Download Docker for your operating system and follow the installation instructions at

Create a new folder where you want to install adaptor:ex.

Open your command line, change to cd the adaptor:ex directory with the command and download the adaptor:ex docker-compose file:

curl -o docker-compose.yml

Run the Docker Compose file:

docker-compose up -d

adaptor:ex server, client, database and plugin extensions will be downloaded and installed.

You can read more about configuring adaptor:ex in the adaptor:ex server readme .

Update with Docker

To update the adaptor:ex Docker installation change to the adaptor:ex directory. Execute the following commands there:

docker-compose pull

and subsequently

docker-compose up -d

First Steps

Enter the URL, i.e. the web address, of your adaptor:ex setup in the web browser.

We recommend using the latest version of Google Chrome or Firefox.

If you have installed adaptor:ex on your computer or laptop with the default settings, you can also click on one of these links: http://localhost:8081 (installation via NPM) or http://localhost:8080 (source installation).

If you have installed adaptor:ex on a server or another computer, you must replace the URL with the IP or domain name of your server.

Create a Game

Die adaptor:ex Startseite

Start by creating a new game project. Click New Game and give your first game a name.

Ein neues Game erstellen

Add levels

If you click on the newly created game project, you will end up in the overview that shows all existing levels. Each game can consist of several levels that are linked in a variety of ways.

Create your first level with Add new.

Games and levels get their own web address through which they can be reached from the web browser. Therefore the name must not contain spaces or special characters.

Name the level and click Add new Level.

Ein Level hinzufügen

Edit level

Then open the level by clicking on the name. You are now in the level editor.

The start ( START ) and end point ( QUIT ) of your level already exist.

Der Level Editor

From the left sidebar, Actions, locate the control action Log Message  and drag and drop it to the middle of the page.

A new State Element is created and contains a Log Message action ( log_1 ).

Eine Action hinzufügen

Click on the new action to edit it. Write a short text in the message input field and select info level from the dropdown .

Eine Action bearbeiten

In order to make your level more understandable, it is good to give all states understandable names.

State names must also not contain spaces, as they can be used in Variables

Click in the title bar of your Log Message State and rename it.

States umbenennen Also edit the Next action next_1 in the START state by clicking on it. Then select the new state, here HelloWorld , from the dropdown to next state connect it to the START state.

2 States verbinden

Start Level

Switch from editing to Live Mode by clicking the play button in the top right corner.

Live Modus Toggle

The left sidebar with the actions closes and a menu opens on the right sidebar.

Click on the right sidebar Create Session and then click to Start Session create a Session from your level.

Eine Session starten

The newly started session is selected in the right sidebar.

Eine session auswählen

The HelloWorld State is already highlighted.

When we create a new session from a level, the START state is triggered automatically. The next_1 action immediately continued to our state HelloWorld with the log message.

Open the log console by clicking on the cursor icon.

Log Konsole anzeigen

The latest log message should say 'Hello World!'.

By clicking on the HelloWorld status you can manually reactivate it. Observe the log console to view the message.

automate levels

Switch back to edit mode by clicking the Live Play button again.

Find the TimeOut action in the right sidebar and drag it into the START State.

If you drag the action over it, the state will be highlighted, indicating that the action will be added to that state instead of creating a new state.

If we add an action to a state that is waiting for something, like a timer to expire, it automatically replaces any Next action.

Edit the timeout. Enter a small number of seconds in the timeout field and choose the HelloWorld State as next state.

Einen timeout erstellen

Also add a timeout action to the HelloWorld state. Edit the timeout and this time select Quit as next state.

If you now switch to live mode and start a new session, the states will be triggered one after the other at fixed intervals.

Mehrere Sessions gleichzeitig

As soon as the QUIT state is reached, the session is terminated and disappears from the right sidebar.

Your first session will not end automatically. To end it you can close it (x) in the right sidebar or trigger the QUIT state when you have selected the session.

Each session is always based on the latest version of the level. However, if the state a session is in changes, it must be triggered again.

Next Steps

In the Glossary you can find out more about the different basic building blocks of adaptor:ex.

Tutorials guide you step by step through projects that you can implement with adaptor:ex.

For example, learn how to use the Telegram plugin to develop a messenger adventure: Storytelling with Telegram and adapter eX

Or start driving an Arduino with adaptor:ex: Arduino Serial

Authors and Supporters

This is a machina commons project by machina eX .

sponsored by

Logo Senatsverwaltung für Kultur und Europa Berlin

Senate Department for Culture and Europe Berlin